ATSUUnhighlightText

OSStatus ATSUUnhighlightText (
                     ATSUTextLayout iTextLayout,
                     ATSUTextMeasurement iTextBasePointX,
                     ATSUTextMeasurement iTextBasePointY,
                     UniCharArrayOffset iHighlightStart,
                     UniCharCount iHighlightLength);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iTextBasePointX

A value of type ATSUTextMeasurement. Pass the x-coordinate of the origin of the line (in the current graphics port) containing the range of text that you want to unhighlight. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want to remove highlighting relative to the current pen location in the current graphics port.

iTextBasePointY

A value of type ATSUTextMeasurement. Pass the y-coordinate of the origin of the line (in the current graphics port) containing the range of text that you want to unhighlight. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want to remove highlighting relative to the current pen location in the current graphics port.

iHighlightStart

A value of type UniCharArrayOffset. Pass the edge offset that corresponds to the beginning of the range of text that you want to unhighlight. If the range of text spans multiple lines, you should call ATSUUnhighlightText for each line and pass the offset of the beginning of the new line you want to unhighlight. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iHighlightLength parameter. If the offset is outside the text buffer, ATSUUnhighlightText returns the result code kATSUInvalidTextRangeErr.

iHighlightLength

A value of type UniCharCount. Pass the length of the range of text that you want to unhighlight. To indicate the end of the text buffer, pass the constant kATSUToTextEnd, described in Text Length Constant. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iHighlightStart parameter. If the range of text is outside the text buffer, ATSUUnhighlightText returns the result code kATSUInvalidTextRangeErr.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache. This may be because the format of the cached data does not match that used by ATSUI or the cached data is corrupt. The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUUnhighlightText function removes highlighting from a specified range of text using the highlight information in the graphics port.

Before calculating the dimensions of the highlighting region to remove, ATSUUnhighlightText turns off any previously set line justification, rotation, width alignment, descent, and ascent values and treats the text as a single line. It then examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUUnhighlightText assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUUnhighlightText assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUUnhighlightText assigns the remaining characters to the last style run it can find.

If you want to remove highlighting from a range of text that spans multiple lines, you should call ATSUUnhighlightText for each line of text that is being unhighlighted, even if all the lines are in the same text layout object. You should adjust the iHighlightStart parameter to reflect the beginning of each line to be unhighlighted.

You can remove highlighting across tab stops by setting the bits specified by the mask constants kATSLineFillOutToWidth and kATSLineImposeNoAngleForEnds, described in Line Layout Option Mask Constants.

ATSUUnhighlightText uses the previously set line ascent and descent values to calculate the height of the highlight region to be removed. If these values have not been set for the line, ATSUUnhighlightText uses the line ascent and descent values set for the text layout object containing the line. If these are not set, it uses the default values.

SPECIAL CONSIDERATIONS

ATSUUnhighlightText may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.